NAME¶

PAPI_get_substrate_info - get information about the software substrate

SYNOPSIS¶

C Interface

#include <papi.h>
const PAPI_substrate_info_t *PAPI_get_substrate_info(void);

Fortran Interface

<none>

DESCRIPTION¶

This function returns a pointer to a structure containing detailed information about the software substrate on which the program runs. This includes versioning information, preset and native event information, details on event multiplexing, and more. For full details, see the structure listing below.

RETURN VALUES¶

On success, the function returns a non-NULL pointer. On error, a NULL pointer is returned.

ERRORS¶

<none>

EXAMPLE¶

const PAPI_substrate_info_t *sbinfo = NULL;
	
if (PAPI_library_init(PAPI_VER_CURRENT) != PAPI_VER_CURRENT)


  exit(1);
if ((sbinfo = PAPI_get_substrate_info()) == NULL)


  exit(1);
printf("This substrate supports %d Preset Events and %d Native events.0,


   sbinfo->num_preset_events, sbinfo->num_native_events);

DATA STRUCTURE¶

The C data structure returned by this function is found in papi.h and reproduced below:

   typedef struct _papi_substrate_option {


     char name[PAPI_MAX_STR_LEN];            /* Name of the substrate we're using, usually CVS RCS Id */


     char version[PAPI_MIN_STR_LEN];         /* Version of this substrate, usually CVS Revision */


     char support_version[PAPI_MIN_STR_LEN]; /* Version of the support library */


     char kernel_version[PAPI_MIN_STR_LEN];  /* Version of the kernel PMC support driver */


     int num_cntrs;               /* Number of hardware counters the substrate supports */


     int num_mpx_cntrs;           /* Number of hardware counters the substrate or PAPI can multiplex supports */


     int num_preset_events;       /* Number of preset events the substrate supports */


     int num_native_events;       /* Number of native events the substrate supports */


     int default_domain;          /* The default domain when this substrate is used */


     int available_domains;       /* Available domains */ 


     int default_granularity;     /* The default granularity when this substrate is used */


     int available_granularities; /* Available granularities */


     int multiplex_timer_sig;     /* Signal number used by the multiplex timer, 0 if not */


     int multiplex_timer_num;     /* Number of the itimer or POSIX 1 timer used by the multiplex timer */


     int multiplex_timer_us;   /* uS between switching of sets */


     int hardware_intr_sig;       /* Signal used by hardware to deliver PMC events */


     int opcode_match_width;      /* Width of opcode matcher if exists, 0 if not */


     int reserved_ints[4];        


     unsigned int hardware_intr:1;         /* hw overflow intr, does not need to be emulated in software*/


     unsigned int precise_intr:1;          /* Performance interrupts happen precisely */


     unsigned int posix1b_timers:1;        /* Using POSIX 1b interval timers (timer_create) instead of setitimer */


     unsigned int kernel_profile:1;        /* Has kernel profiling support (buffered interrupts or sprofil-like) */


     unsigned int kernel_multiplex:1;      /* In kernel multiplexing */


     unsigned int data_address_range:1;    /* Supports data address range limiting */


     unsigned int instr_address_range:1;   /* Supports instruction address range limiting */


     unsigned int fast_counter_read:1;     /* Supports a user level PMC read instruction */


     unsigned int fast_real_timer:1;       /* Supports a fast real timer */


     unsigned int fast_virtual_timer:1;    /* Supports a fast virtual timer */


     unsigned int attach:1;		   /* Supports attach */


     unsigned int attach_must_ptrace:1;	   /* Attach must first ptrace and stop the thread/process*/


     unsigned int edge_detect:1;           /* Supports edge detection on events */


     unsigned int invert:1;                /* Supports invert detection on events */


     unsigned int profile_ear:1;      	   /* Supports data/instr/tlb miss address sampling */


     unsigned int grouped_cntrs:1;         /* Underlying hardware uses counter groups */


     unsigned int reserved_bits:16;


   } PAPI_substrate_info_t;

BUGS¶

If called before PAPI_library_init() the behavior of the routine is undefined.

SEE ALSO¶

PAPI_library_init(3), PAPI_get_opt(3), PAPI_get_dmem_info(3), PAPI_get_hardware_info(3), PAPI_get_executable_info(3)